<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
	<title>Getting Started with KMLigPlugIn</title>
	<link rel="STYLESHEET" href="/stylesheets/rbnbstyles.css" type="text/css" />
</head>
<body>
<h1>Getting Started with KMLigPlugIn</h1>

<p>KMLigPlugIn processes image data for display in Google Earth. A sequence 
of jpeg images and camera metadata in RBNB channels is combined into a 
Google Earth KMZ archive containing a KML and image files. The images 
are displayed as "billboards", with a time slider to move through the 
images.

<p>The PlugIn takes as input images and metadata from RBNB channels. A 
camera's position, orientation, field of view, and image display 
parameters are used to appropriately locate the images within Google 
Earth. This information is stored in a metadata channel in the same RBNB 
folder as the images. If the camera or its field of view change with 
time, the metadata can be updated along with the images. By convention, 
for an image channel named "folder/image.jpg", the metadata channel 
would be "folder/image.xml". An example metadata is shown in Figure 1. 
The &lt;name&gt; element specifies how the PhotoOverlay should be labeled in 
Google Earth. The &lt;Camera&gt; element specifies where the camera is 
positioned and how it is oriented. The &lt;ViewVolume&gt; element specifies 
how images are displayed relative to the camera. The &lt;Point&gt; element 
specifies where the icon for the PhotoOverlay is displayed in Google 
Earth. In practice, the camera's location can be determined via GPS, 
field observation, or approximated by manipulation within Google Earth 
to closely overlay the maps and added structures.

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;Meta&gt;
	&lt;name&gt;CollisPO&lt;/name&gt;
	&lt;Camera&gt;
		&lt;longitude&gt;-72.28889252700002&lt;/longitude&gt;
		&lt;latitude&gt;43.703&lt;/latitude&gt;
		&lt;altitude&gt;7&lt;/altitude&gt;
		&lt;heading&gt;-95.37000000000015&lt;/heading&gt;
		&lt;tilt&gt;90&lt;/tilt&gt;
		&lt;roll&gt;0&lt;/roll&gt;
	&lt;/Camera&gt;
	&lt;ViewVolume&gt;
		&lt;leftFov&gt;-30&lt;/leftFov&gt;
		&lt;rightFov&gt;30&lt;/rightFov&gt;
		&lt;bottomFov&gt;-22.5&lt;/bottomFov&gt;
		&lt;topFov&gt;22.5&lt;/topFov&gt;
		&lt;near&gt;20&lt;/near&gt;
	&lt;/ViewVolume&gt;
	&lt;Point&gt;
		&lt;coordinates&gt;-72.2888925270,43.70291,10.36999999&lt;/coordinates&gt;
	&lt;/Point&gt;
&lt;/Meta&gt;
</pre>

<p><b>Figure 1. An example metadata for a camera, which specifies the camera's 
position, orientation, field of view, and image display parameters.</b></p>

<p>The PlugIn generates KML by using template files, which are included in 
the RBNB distribution and automaticallly loaded at runtime. KML2.2 added 
the PhotoOverlay element, which allows for images to be displayed within 
Google Earth in a greatly simplified manner compared to the DAE file 
approach supported in earlier versions. The KMLigPlugIn takes advantage 
of this new capability, providing the functionality of the KMLitPlugIn 
with far less complexity.

<p>The output of the KMLigPlugIn is a KMZ archive, which contains single 
KML file and multiple images. In response to a request, the KMLigPlugIn 
requests images and metadata from the RBNB server. Values from the 
metadata are substituted into the template format of the kml file. This 
template format is defined in two files, kml.kml and photooverlay.kml. 
Substitutions are made to variables denoted by "##" encasement. The 
template files are shown in Figures 2 and 3. These template files may be 
edited, allowing flexibility in deployment. For example, the icon can 
readily be customized.

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;kml xmlns=&quot;http://earth.google.com/kml/2.2&quot;&gt;
&lt;Document&gt;##photooverlay##&lt;/Document&gt;
&lt;/kml&gt;
</pre>

<p><b>Figure 2. Template file used to generate kml content.</b></p>

<pre>
&lt;PhotoOverlay&gt;
	&lt;name&gt;##name##&lt;/name&gt;
	&lt;description&gt;autogenerated by KMLigPlugIn&lt;/description&gt;
	&lt;TimeSpan&gt;
		&lt;begin&gt;##begin##&lt;/begin&gt;
		&lt;end&gt;##end##&lt;/end&gt;
	&lt;/TimeSpan&gt;
	&lt;Camera&gt;
		&lt;longitude&gt;##clongitude##&lt;/longitude&gt;
		&lt;latitude&gt;##clatitude##&lt;/latitude&gt;
		&lt;altitude&gt;##caltitude##&lt;/altitude&gt;
		&lt;tilt&gt;##ctilt##&lt;/tilt&gt;
		&lt;heading&gt;##cheading##&lt;/heading&gt;
		&lt;roll&gt;##croll##&lt;/roll&gt;
	&lt;/Camera&gt;
	&lt;Style&gt;
		&lt;IconStyle&gt;
			&lt;Icon&gt;
				&lt;href&gt;http://maps.google.com/mapfiles/kml/shapes/camera.png&lt;/href&gt;
			&lt;/Icon&gt;
		&lt;/IconStyle&gt;
	&lt;/Style&gt;
	&lt;Icon&gt;
		&lt;href&gt;##href-jpg##&lt;/href&gt;
	&lt;/Icon&gt;
	&lt;shape&gt;rectangle&lt;/shape&gt;
	&lt;ViewVolume&gt;
		&lt;near&gt;##vnear##&lt;/near&gt;
		&lt;leftFov&gt;##vleftfov##&lt;/leftFov&gt;
		&lt;rightFov&gt;##vrightfov##&lt;/rightFov&gt;
		&lt;bottomFov&gt;##vbottomfov##&lt;/bottomFov&gt;
		&lt;topFov&gt;##vtopfov##&lt;/topFov&gt;
	&lt;/ViewVolume&gt;
	&lt;roll&gt;0&lt;/roll&gt;
	&lt;Point&gt;
		&lt;coordinates&gt;##coordinates##&lt;/coordinates&gt;
	&lt;/Point&gt;
&lt;/PhotoOverlay&gt;
</pre>

<p><b>Figure 3. Template file used to generate PhotoOverlay elements within 
kml files.</b></p>

<p>The output of KMLigPlugIn can also be adjusted on a per-request basis. 
The maximum number of images and minimum interval between images can be 
specified by URL munges. The parameters are kmlit_count and 
kmlit_interval, respectively. For example, a URL specifying no more than 
30 images over a 120 second request is:

<p><center>
http://someplace.com/RBNB/KMLig/Collis/Collis.jpg?d=120&amp;kmlit_count=30
</center></p>


